Frameworks/Adium Framework/Source/KFTypeSelectTableView.h

   1 //
   2 //  KFTypeSelectTableView.h
   3 //  KFTypeSelectTableView v1.0.4
   4 //
   5 //  Keyboard navigation enabled table view.  Suitable for
   6 //  class posing as well as normal use.
   7 //
   8 //  All delegate methods are optional, except you need to implement typeSelectTableView:stringValueForTableColumn:row:
   9 //  if you're using bindings to supply the table view with data.
  10 //
  11 //  ------------------------------------------------------------------------
  12 //  Copyright (c) 2005, Ken Ferry All rights reserved.
  13 //
  14 //  Redistribution and use in source and binary forms, with or without
  15 //  modification, are permitted provided that the following conditions are
  16 //  met:
  17 //
  18 //  (1) Redistributions of source code must retain the above copyright notice,
  19 //      this list of conditions and the following disclaimer.
  20 //
  21 //  (2) Redistributions in binary form must reproduce the above copyright
  22 //      notice, this list of conditions and the following disclaimer in the
  23 //      documentation and/or other materials provided with the distribution.
  24 //
  25 //  (3) Neither Ken Ferry's name nor the names of other contributors
  26 //      may be used to endorse or promote products derived from this software
  27 //      without specific prior written permission.
  28 //
  29 //
  30 //  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  31 //  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  32 //  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  33 //  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
  34 //  OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  35 //  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  36 //  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  37 //  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  38 //  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  39 //  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  40 //  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41 //
  42 //  ------------------------------------------------------------------------
  43 //
  44
  45 #import <Cocoa/Cocoa.h>
  46
  47 #pragma mark constants
  48
  49 typedef enum KFTypeSelectMatchAlgorithm {
  50     KFSubstringMatchAlgorithm = 0,
  51     KFPrefixMatchAlgorithm = 1
  52 } KFTypeSelectMatchAlgorithm;
  53
  54 @interface KFTypeSelectTableView : NSTableView
  55
  56 #pragma mark action methods
  57
  58 // these beep if the operation cannot be performed
  59 - (void)findNext:(id)sender;
  60 - (void)findPrevious:(id)sender;
  61
  62 #pragma mark accessors
  63 // KVO-compliant
  64 - (NSString *)pattern;
  65
  66 // a tableview with no match algorithm set uses defaultMatchAlgorithm
  67 // defaultMatchAlgorithm defaults to KFPrefixMatchAlgorithm
  68 + (KFTypeSelectMatchAlgorithm)defaultMatchAlgorithm;
  69 + (void)setDefaultMatchAlgorithm:(KFTypeSelectMatchAlgorithm)algorithm;
  70
  71 - (KFTypeSelectMatchAlgorithm)matchAlgorithm;
  72 - (void)setMatchAlgorithm:(KFTypeSelectMatchAlgorithm)algorithm;
  73
  74 // defaults to NO
  75 - (BOOL)searchWraps;
  76 - (void)setSearchWraps:(BOOL)flag;
  77
  78 // supply a set of identifiers to limit columns searched for match.
  79 // Only columns with identifiers in the provided set are searched.
  80 // nil identifiers means search all columns.  defaults to nil.
  81 - (NSSet *)searchColumnIdentifiers;
  82 - (void)setSearchColumnIdentifiers:(NSSet *)identifiers;
  83
  84 @end
  85
  86 @interface NSObject (KFTypeSelectTableViewDelegate)
  87
  88 #pragma mark configuration methods
  89
  90 // Implement this method if the table uses bindings for data.
  91 // Use something like
  92 //     return [[[arrayController arrangedObjects] objectAtIndex:row] valueForKey:[column identifier]];
  93 // Could also use it to supply string representations for non-string data, or to search only part of visible text.
  94 - (NSString *)typeSelectTableView:(id)tableView stringValueForTableColumn:(NSTableColumn *)column row:(int)row;
  95
  96 // defaults to YES
  97 - (BOOL)typeSelectTableViewSearchTopToBottom:(id)tableView;
  98
  99  // defaults to first or last row, depending on direction of search
 100 - (int)typeSelectTableViewInitialSearchRow:(id)tableView;
 101
 102 // A hook for cases (like mail plugin) where there's no good place to configure the table.
 103 // Will be called before type-select is used with any particular delegate.
 104 - (void)configureTypeSelectTableView:(id)tableView;
 105
 106 #pragma mark reporting methods
 107 // pattern of @"" indicates no search, anything else means a search is in progress
 108 // userInfo dictionary has @"oldPattern" key
 109 // this notification is sent
 110 //    when a search begins or is modified
 111 //    when a search is cancelled
 112 //    x seconds after a search either succeeds or fails, where x is a timeout period
 113 - (void)typeSelectTableViewPatternDidChange:(NSNotification *)aNotification;
 114 - (void)typeSelectTableView:(id)tableView didFindMatch:(NSString *)match range:(NSRange)matchedRange forPattern:(NSString *)pattern;
 115 - (void)typeSelectTableView:(id)tableView didFailToFindMatchForPattern:(NSString *)pattern; // fallback is a beep if delegate does not implement
 116
 117 @end
 118
 119 #pragma mark notifications
 120 // delegate automatically receives this notification.  See delegate method above.
 121 extern NSString *KFTypeSelectTableViewPattenDidChangeNotification;